0.0 Introduction and History

They say necessity is the mother of invention, and this piece of code
is no exception.  Several months ago, after reflecting on the success
of YAZI, George and I started talking about how we would like to use
our Newtons.  The bottom line seemed to be that we wanted to be able
to use them as "wee little computers" that we could take with us
anywhere. Since we spend most of our time playing on Un*x boxes, it
seems natural to use VT100 as our standard interface to the various
tools we use.

Unfortunately, we were underwhelmed (if that's a word) with the
available products.  The biggest problem is that they were far too
slow -- they would timeout before we could login!  The other problem
was that the other products just cost too much.

So, instead, we spent several months writing our own!

We designed PT100 for ourselves: to provide basic VT100 support in a
small, fast, inexpensive product. Non-critical features have been
excluded.  If you feel something important is missing, please drop us
a line so we can discuss the new feature.

As you read through the following documentation, realize that we
originally designed this product for ourselves, to solve problems we
were having, and have more recently begun to support various options
other folks may want.  If something critical to your application is
missing, please drop us a line so we can discuss how to remedy the
oversight.



1.0 About PT100

PT100 is a VT100 emulator for the Newton, capable of Modem, Direct
Serial and Telnet sessions.  VT100 emulation is the most common
text-based interface on the Internet, as well as the standard used by
BBSes, corporate systems, various email mechanisms and many online
services.  In addition, it is useful for many types of straight serial
connectivity.

PT100 is the only VT100 emulator on the Newton capable of providing
Telnet capability with Newton Internet Enabler (NIE).  PT100 requires
Newton OS 2.X and supports and takes advantage of many of the advanced
features of the eMate 300 and the MP2000. .  For telnet access, an
MP130, MP2000 or an eMate 300 is recommended.

PT100 ©1997 Scrawl.  All Rights Reserved.  PT100 was written by George
Madrid and Sanjay Vakil.


2.0 Setup a Session

To set up a session, click on the Connect or Command button and select
Edit Sessions.  If you have not already created a session, a blank one
will appear for you to edit.  You can change the session that your are
editing by clicking on the Session popup.  The routing button
(envelope) allows you to copy the current session, delete it, or
create a new blank session.

Once you have selected the session to edit, you will need to name it,
and select the Type (Modem, Direct Serial or Telnet). If you wish, you
can enter your username and password to have them available for quick
input.  The password will be encrypted on the Newton and will be
decrypted before it is sent.  If you are paranoid, don't enter a
password at all.  A password can easily be entered manually.

Based on the type of session you selected, additional options will
appear, specific to the type of session. See the next sections on
additional information that might be necessary.


2.1 Setting up a Modem Session

For a Modem Session, you will need to enter a phone number and the
various modem parameters. If these are not correctly set, you may not
be able to connect.  However, incorrect parameters should not damage
your Newton or your modem, so you may want to experiment to get the
correct values.

Reasonable values for this parameters are as follows:

Speed: the fastest rate that you modem can handle (if necessary, the
modem will slow down to the speed of the service automatically)

Flow Control: Hardware

Error Correction: Selected

Data Bits / Parity / Stop Bits: Common triplets are 8N1 and 7E1

If you are unsure about the correct parameters, try contacting the
service you intend to connect with to determine their suggested
parameters, or experiment.


2.2 Setting up a Direct Serial Session

For a Direct Serial Session, you will need to set a number of serial
parameters.  If these are not correctly set, you may receive garbled
output, if any at all.  However, incorrect parameters should not
damage your Newton or the other device, so you may to experiment to
get the correct values.

Reasonable values for this parameters are as follows:

Speed: Read the manual for the device with which you are connecting.
Or, if you built it yourself, you should know (:

Flow Control: Hardware if you are using a full RS232 connection,
software if you only have a 2 or 3 wire connection.

Data Bits / Parity / Stop Bits: Common triplets are 8N1 and 7E1

If you are unsure about the correct parameters, try consulting the
manual of the device with which you intend to connect.

In addition, you can explicitly select the serial port that you wish
to use.  On current Newtons, this can involve selecting between the
external serial port and the PC card slot(s).  This can be very useful
if you need to connect directly to PC card devices, such as oddball
cellular modems.

Astute users will note that "IR Port" appears on the list. We make no
guarantees about what this will do.  We'd love to know if you get it
to do something useful!


2.3 Setting up a Telnet Session

For a Telnet Session, you will need to select a machine name to telnet
to, and a port number.  You should enter the full machine name,
including the domain, for example "sanj-o-matic.mit.edu".  An IP
address (for example 127.0.0.0) associated with the machine name is
looked up by the Newton.  If you know the machineŐs IP address, you
can enter it instead of the name.

A port number is a numeric identifier of the specific TCP/IP port to
which you wish to connect.  The standard port number for telnet is 23,
though if you want to do cool things like getting to finger (79), smtp
(25), or web (80) port, you can select that instead.

The other setup options for Telnet Sessions (phone numbers, ISP, etc.)
are controlled by the Newton Internet Enabler (NIE).  Consult your NIE
documentation and setup program for additional information.


2.4 Session Setup Tips

A new session created by using Blank Session will default to a
standard set of options.

If you have already created a working session tailored to your
specific modem, Newton and service combination, it may be faster to
simply use Duplicate Session to create a new session.  You only need
to update the options that are different, such as the username and
password.

If you have differing users of the same Newton, you can create a
different session for each user.  Make sure you name each session in a
way that makes it apparent which user's session it is.


3.0 Connect to a Service

To connect to a service, tap on Connect on the status line. A slip
will appear, from which you can select a session.  If you need to edit
the calling slip to use a calling card or attach a prefix before
dialing, click the Assist button.

Once you have selected the session you wish to connect to, press
Connect on the slip.  The progress of the connection status will
appear on the slip.

If you are connecting with a Telnet Session, clicking Connect will pop
up the NIE slip box, in which you can select your service provider and
associated phone number. Click the Connect button on the NIE slip to
initiate the call.


4.0 Disconnect from a Service

To disconnect from a service, tap on Hangup on the status line.  A
slip will appear, showing the connection being broken, and will prompt
you when the Newton is available to connect once more.

Exiting PT100 will also disconnect.  Note that you will have to
disconnect before your Newton will turn off.


5.0 Inputing Data

There are several ways to input data in PT100.  The easiest
(and default) manner is to write words onto the input line.
For control codes and difficult-to-write characters, you can
use an from multiple onscreen keyboards or use the Newton
keyboard.  Finally, you can choose to have no onscreen input
area at all.

To switch between the different modes, press the Keyboard icon on the
status bar.


5.1 Using the Input Line

To use the input line, simply write what you wish to send, and press
Send.  The popup diamond allows quick access to an editable set of
common words.  The word you select will be appended to the input line.
This list also allows you to easily send your username and password.

The size of the input line can be changed in the Prefs, available from
the Info button.


5.2 Editing the Popup List

To edit the list of words, click on the diamond and select Edit List.
A slip will appear to allow you to edit individual words.

To add a new entry, write it on the input line and press Add.  To
examine the list, click on Available Words.  To delete an entry,
select it with Available Words and then press Delete.


5.3 Using the Onscreen Keyboards

To use the onscreen keyboard, select Keyboard from the Keyboard button
on the status line. Simply type on the keyboard as you normally would.

In addition, you can load additional "Plug In" keyboards for
specialized use.  With this distribution, you should find several
different keyboards, including one designed explicitly for VT100
emulation, a "full" VT100 keyboard with numeric keypad, and others.
You may also be interested in application custom keyboards, such as
the Lynx keyboard, also included in this distribution.  If installed,
these keyboards will also show up in the Keyboard button.  On many
keyboards, the ALT key will prefix an ESC to a keystroke for Un*x
users.

The QuickPicker is available (and very useful) when using onscreen
keyboards.


5.4 Using the Hardware Keyboard

A hardware keyboard can be used in two ways with PT100.  It can be
used either to type into the input line (buffered), or to directly
send characters (unbuffered).  For buffered input, simply select the
input line and type away.

For unbuffered input, select Keyboard or None from the Keyboard button
on the status line and type normally.  The alt key will prefix an ESC
to a keystroke for Un*x users, and an ESC on its own can be created
with CTRL-[.

Note that you can use the hardware keyboard concurrently with the
software and plug in keyboards for additional functionality.


5.5 Using the QuickPicker

On the status line, there is a popup diamond that allows access to
common words used with the input line.  Selecting an entry from this
list sends it directly to the session, without having to press Send.

The last few lines of the QuickPicker work differently than the
editable ones.  After the dotted line will be the most recently sent
string, either selected with the QuickPicker, or sent with the Input
Line.  The next two entries will send your username or password.  Be
wary -- sending a password at the wrong time will blast it to the
screen.

The QuickPicker is particularly handy if you have the input area
minimized to allow full-screen viewing.


5.6 Sending Returns with the Send Button

After you write something on the input line, you can choose to have it
sent with a carriage return appended or without .

To toggle between these two modes, press the Return arrow next to
Send.  When it is lit a carriage return will be sent with both the
QuickPicker and the input line.


5.7 Input Tips

Since it is quick and easy to change the words in the QuickPicker, it
makes sense to modify it regularly to make it useful from session to
session.  If you use a command regularly, write it into the input
line, press Edit Sessions and then Add.  In a few short taps you've
added a new entry to the QuickPicker.

For many users, having quick access to a space character is useful.
Adding this to the QuickPicker looks odd (it's an empty line!), but
can save you from pulling up the keyboard regularly.

PT100 is capable of "drag and drop" operation as well.  Any text that
is on the clipboard (dragged to the edge of the screen) can be
dropped onto the screen output area and will be sent.

In addition, if the notepad is currently open, you can send the current
note by tapping on the Action button and selecting "Send Note".  Currently,
you can only send plain text notes, no checklists or outlines.


5.8 Advanced Input: Parsing

Text input can be parsed to allow control characters to be sent
without using the keyboard. A circumflex indicates that a control
character should be sent, so that ^g will send the Bell, and 
^[ will send ESC.  This can be very useful for sending control
codes when you don't have keyboard connected.

Text input that contains material inside double-quotes will ignore
anything outside the quotes.  This can be very useful, as it allows
you to label commands that contain fancy control information:

save: "^x^s"
load: "^x^f"

To circumvent these behaviors, use a backslash to escape the
character:

- to send a ", type \"
- to send a ^, type \^
- to send a \, type \\

To turn on this parsing, select "Parse Output" in the preferences.


5.9 Floating Input Area

Some users may want a floating input area rather than one that
explicitly uses up part of the screen.  In PT100->Prefs->Input, there
is an option for "Floating Input Area".  Checking this box will cause
all input options (keyboards and input lines) to float above the rest
of the view.  This floater can be dragged around, even off screen to
maximize the available space on the screen.

In the bottom right corner of a floating input are will be a minimize
button.  Pressing this will temporarily hide the input area and change
the Keyboard button into a "floater" symbol.  To bring back the hidden
keyboard, tap on the Keyboard button.


6.0 Move Around the Screen

In many cases, the Newton screen (especially in portrait orientation)
is too small to fit all the text on the screen at one time.  PT100
overcomes this problem by showing a portion and allowing you to move
the text to see offscreen information.

To move text you can either use the onscreen compass (if it is
visible) or you can click on the text and "drag" it around.  Using the
compass moves the screen in set increments:  eight characters or one
line at a time.

If you grow tired of moving around the screen, you can try switching
to a smaller font, or rotating the screen.


7.0 Change the Font or Screen Size

To change the currently displayed font, select Prefs from the Info
button.  You can select from any of the installed monospaced fonts and
sizes.  Note that certain ill-formed monospaced fonts may not display
information correctly in bold.  The Minico font that came with PT100
is specially designed to allow accurate output.

While easier on the eyes, larger fonts may require you to move the
screen around to see all the information.

You can also select the number of input lines available, screen width
and screen height.  Changing the width and height may cause odd
wrapping if you select less than the standard 80x24.  If you have the
ability to tell the computer on the other end that you have changed
the screen size, do so before resizing the PT100 screen.


8.0 Save Output

To save output is to use the Copy to Notes entry in the Connect or
Command button. This will copy the current screen to a new unfiled
note in the Notepad preserving the font, but not attributes such as
inverse, bold and underline.  If you are scrolled back, the page that
you see will be stored.


9.0 Preferences

There are four separate sets of preferences in PT100.  While most of
these are self-explanatory, a few need more information.

Update Times: Comms Update determines how fast a non-terminated line
will display. The lower you set this, the faster the Newton looks for
incomplete lines.  A value that is too low may slow your Newton down.

Screen Update determines how quickly the Newton will refresh the
screen with new information. Too low a value may slow your Newton down
as it refreshes too often.

Marginal Modem:  Certain older modems, notably the Compaq 24/96 modem,
provide only marginal Newton support. Checking the Marginal Modem box
will let PT100 work in many situations, though not all. For example, 7
Data Bits will not work with this option enabled.

Cover Soft Button Bar: To maximize screen space on MP2000s and future
Newtons with soft button bars, you can have PT100 cover this.  Note
that this removes access to the Extras drawer and associated
functions.

Don't Turn Off While Connected:  Checking this option will prevent the
Newton from powering down while you are connected.  This is helpful if
you are in the habit of accidentally shutting off the Newton when you
try to turn on the backlight.


10.0 About PT100Ős Cripple

PT100 is crippled shareware.  Unregistered versions of PT100 will only
be allowed five minutes of connection time per session. After a
warning at the four-minute mark, the application will hang up at the
five-minute mark. You may redial and start another session.

If you intend to use an unregistered version of PT100 in a critical
situation, please be sure to save your work. Better yet, if you're
using it for critical work, pay for it.

11.0 Register PT100

To register PT100, send $25 to:

Sarah Buta c/o Scrawl 
86 Norfolk St., Apt. 4 
Cambridge, MA 
02139-2652

Be sure to include the spelling of your name as it appears on your
Newton.  You will receive a registration string by email. If you do
not have email, send a SASE. Alternately, you can use Kagi with Flash
SheridanŐs Register.


12.0 Register PT100 via WWW Kagi

You can Register PT100 directly over the WWW by using Kagi. For more
information about Kagi, visit: 

<http://www.kagi.com>

You can register PT100 directly over the Web at:

<http://kagi.direct.net/cgi-bin/register1.cgi?JV>


13.0 Contact Scrawl

You can visit Scrawl at: <http://www.scrawlsoft.com> or send email to:
<help@scrawlsoft.com>


14.0 Frequently Asked Questions


Q: Will you support 1.X Newtons?

A: It is unlikely that PT100 will ever support 1.X machines. Many of
the tools used to get maximum performance out of the system are
2.0-specific.  You might try looking at at some of the other emulators
available for the Newton.

Q: What about support for VT220, Tek and other emulators?

A: At the moment PT100 is highly focused on speedy and accurate VT100
emulation, because it is the largest common denominator for text
interfaces.  If another interface becomes necessary and has a large
enough market, it will be considered.

Q: My modem is not directly Newton supported and needs special setup
strings.  Can I use PT100 on it?

A: You can certainly use it as a serial device by entering your own
setup strings.  Fundamentally, however, you should use a supported
modem for your Newton.  It will make you life much easier.

Q: What about login scripts?

A: Support for creating login scripts is on the list of features for
upcoming releases.  Please write to us if this is a key feature for
your use of PT100.

Q: Odd things are happening when I use certain programs. How complete
is the VT100 emulation?

A: As mentioned earlier, PT100 was designed as tool for personal use.
As such, we have implemented VT100 emulation elements as we require
them, and have the ability to test them.  If certain elements are
missing, it may be because those elements were not used by the
programs we used to test it.  If a particular emulation problem is
repeatable, and shows up in a program which you use, please write to
us, and we'll look into updating the emulation.  We hope, at some
future date, to have complete VT100 emulation in PT100, but expect the
vast majority of people can use it comfortably in the interim.

Q: Can I scroll back and see stuff that went off the top of the
screen?

A: Yep.  Turn the Scroll Back to some number greater than zero.  Then
use the up and down arrows (not the compass) to scroll back.

Q: What about support for the MP2000 and the eMate 300?

A: PT100 has been casually tested on both these machines, and it works
flawlessly.  On the MP2000, the application runs about 8x faster; on
the eMate about 3x faster.

Q: These custom floating keyboards are very useful!  Can you design
one for my particular [email|database|browser] application?

A: We probably can.  Contact us and we can discuss pricing and
distribution.  Also see the next question.

Q: These custom floating keyboards are very useful!  I'm a newton
programmer and would like the API so I can design my own, perhaps
for some vertical market applications I'm working on.  Are you
interested?

A: We sure are!  Contact us and we can discuss pricing and
distribution.  Also see the previous question.

Q: I need a specific vertical market application that will use a
textual front end.  Are you guys interested in extra work?

A: Contact us, we just might be!

Q: How about multiple simultaneous telnet sessions?

A: Jeepers!  You want it all!  In good time we hope to have this
capability, but for right now, chill out and enjoy what PT100 does do!


15.0 Trouble Shooting

Problem: PT100 doesn't work!

Solution: Does too!  Seriously, check to make sure that all your
cables are plugged in, and your PC card modem is installed, and locked
into the card slot.  Check that your modem is plugged into the phone
line and that the line is working.

Problem: PT100 still doesn't work!

Solution: Does anything on the Newton work with your modem? If, when
you insert the PC card, the Newton doesn't acknowledge that you did
so, you're out of luck.  If the Newton recognizes that a
communications card has been inserted, try to dial a number with the
Calls applicaton or try to send a fax.  If this fails, you do not have
the correct Modem Setup for your modem.  Check the Apple web pages
<http://devworld.apple.com/dev/newton/commsoln/modsetup.html> for the
list of supported modems and links to Modem Setup files.  Alternately,
you can try to roll your own Modem Setup by using ModemMod from DMP
Systems <http://www.netacc.net/~dmpsyst/>.  Be sure to pay the
shareware fee if you find it useful.

Problem: My modem doesn't work!

Solution: Certain older modems, notably the Compaq 24/96 modem, provide 
only marginal Newton support. Checking the Marginal Modem box will let 
PT100 work in many situations, though not all. For example, 7 Data Bits 
will not work with this option enabled

We strongly discourage the use of this option. Buy a new modem.

Problem: I'm not getting VT100 emulation.

Solution:  Make sure that you have have told the server the terminal
type that you are using, i.e. VT100.

Problem: PT100 connects for a few seconds, then disconnects, sometimes
with a "I/O Buffer Overflow" error.

Solution: Check to make sure your Modem Setup is correct. Also verify
that you have some sort of flow control (either software or hardware
enabled)

Problem: I get garbage after I connect.

Solution: Try turning on error correction.  New, high speed modems are
pushing the limits of current analogue phone lines, leading to noisy
connection.  Error correction can help a great deal.  Next, make sure
that you have the modem or serial parameters set correctly.

Problem: Telnet doesn't work on my MP120.

Solution:  As with all NIE related software, using Telnet on an MP120
is tricky at best.  Try freezing, or erasing everything you can.  Try
resetting or rebooting your Newton. We're working very hard to get
this working (since we only own MP120s) but it's difficult.  Don't
hold your breath. Enjoy great shell access instead!

Problem: I can't see all of the text on the screen.

Solution:  Try scrolling around with the compass, setting a smaller
font size, or minimizing the input area by selecting None from the
Keyboard button.  You can also make the input line smaller.

Problem: There don't seem to be any bold characters in the 9 point
Minico font.

Solution:  There aren't.  With only 3 pixels to work in, a bold 9
point font would be unreadable.  If you need to see bold, look at the
text in 10 point.

Problem:  My registration string wasn't accepted.

Solution: Please recheck it and try again.  Make sure that Os and 0s,
ls, 1s and Is are not begin confused.  Verify that the name you sent
us is the same one in the "Owner Info" on your Newton.  If you have
multiple owner cards, try sending us your Newton Serial Code (which
appears in the About Box).

Problem:  Weird characters like "[5;c" sometimes appear on my screen.

Solution: Congratulations!  You've found an oddball VT100 code. Please
send us mail detailing how you caused this problem and win our undying
gratitude, as well as a witty reply.  The exact text of the garbage
would be useful as well.

Problem:  When I dial into a BBS, I don't get nice line drawings, but
a bunch of lowercase letters.

Solution:  The font set required by ANSI compliant BBSes is not yet
completely supported in Minico.  We're working with the designer of
Minico (Michael Peay) to complete the set in all of the used font
sizes.

Problem:  My hardware keyboard isn't working.

Solution:  Your keyboard needs to be plugged into your Newton on
powerup in order to be recognized.  Try turning your Newton on and
off.  In some cases, selecting Input Line, and then None from the
Keyboard button may solve problems.